home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / t3_1 / risc_src.lha / risc_sources / xlib / doc.mss < prev    next >
Text File  |  1990-05-29  |  15KB  |  419 lines
  1. Using the X11 C library from Scheme->C
  2. --------------------------------------
  3.  
  4. One of the goals of the Scheme->C project has been to produce a Lisp which is
  5. able to co-exist with other languages.  One use for such a language is as
  6. "glue" for constructing X window applications. As a first step down this path,
  7. a set of interfaces to X11's Xlib have been generated.  These allow a Scheme
  8. programmer to execute X applications written in Scheme within the Scheme
  9. interpreter, or as stand-alone Scheme programs.
  10.  
  11.  
  12. An Example
  13. ----------
  14.  
  15. Before going into any detail, an example is in order.  This example is a Scheme
  16. version of the initial sample program from Oliver Jones' book, "Introduction to
  17. the X Window System":
  18.  
  19. (module hello
  20.     (main main)
  21.     (with xlib))
  22.  
  23. (define (HELLO-WORLD)
  24.     (let* ((hello "Hello, World")
  25.        (hi "Hi!")
  26.        (dpy (let ((x (xopendisplay "")))
  27.              (if (null-pointer? x)
  28.              (error 'hello-world "DISPLAY is not defined"))
  29.              x))
  30.        (screen (xdefaultscreen dpy))
  31.        (background (xwhitepixel dpy screen))
  32.        (foreground (xblackpixel dpy screen))
  33.        (window (xcreatesimplewindow dpy (xdefaultrootwindow dpy)
  34.                200 300 350 250 5 foreground background))
  35.        (gc (xcreategc dpy window 0 (make-xgcvalues)))
  36.        (event (make-xevent)))
  37.       (xstorename dpy window "Hello, World  in Scheme->C using Xlib")
  38.       (xseticonname dpy window "hello")
  39.       (xsetbackground dpy gc background)
  40.       (xsetforeground dpy gc foreground)
  41.       (xselectinput dpy window (+ buttonpressmask
  42.                         (+ keypressmask exposuremask)))
  43.       (xmapraised dpy window)
  44.       (let loop ()
  45.            (ynextevent dpy event)
  46.            (cond ((eq? (xevent-type event) expose)
  47.               (xdrawimagestring (xevent-xexpose-display event)
  48.               (xevent-xexpose-window event) gc 50 50
  49.               hello (string-length hello))
  50.               (loop))
  51.              ((eq? (xevent-type event) mappingnotify)
  52.               (xrefreshkeyboardmapping event)
  53.               (loop))
  54.              ((eq? (xevent-type event) buttonpress)
  55.               (xdrawimagestring (xevent-xbutton-display event)
  56.               (xevent-xbutton-window event) gc
  57.               (xevent-xbutton-x event) (xevent-xbutton-y event)
  58.               hi (string-length hi))
  59.               (loop))
  60.              ((and (eq? (xevent-type event) keypress)
  61.                (equal? (ylookupstring+ event) "q"))
  62.               (xfreegc dpy gc)
  63.               (xdestroywindow dpy window)
  64.               (xclosedisplay dpy))
  65.              (else (loop))))))
  66.  
  67. (define (MAIN clargs) (hello-world))
  68.  
  69. The window system operations are confined to the procedure HELLO-WORLD.  It
  70. starts with a LET* construct which sequentially binds variables.  DPY is bound
  71. to the display pointer returned by xopendisplay, which is an interface
  72. procedure to XOpenDisplay.  As with other Xlib interfaces to Scheme, the caller
  73. provides a Scheme string when a null-terminated string is expected.  Since
  74. XOpenDisplay returns a single value, it is returned as the value of
  75. xopendisplay. Where possible, the values returned by the Xlib interfaces are
  76. type tagged to allow runtime type checking.  Thus on a successful call to
  77. xopendisplay, one gets back a dotted-pair of the form:  (DISPLAYP . 272961004).
  78. If the display couldn't be opened, then xopendisplay would return (DISPLAYP .
  79. 0) and the predicate NULL-POINTER? would return #T.
  80.  
  81. The creation of the graphics context GC shows two more facets of the Xlib
  82. interface.  First, since all interfaces are type checked as much as possible,
  83. xcreategc wants not just any pointer, but a pointer to an XGCValues struct as
  84. one of its arguments.  In order to create an instance of that struct, one calls
  85. make-xgcvalues which returns a dotted pair of the form: (XGCVALUESP . "").
  86. There, the identifier identifies the type of object, and the string is the
  87. object.
  88.  
  89. Following the creation of an XEvent struct, the window is decorated, events
  90. selected, and then the window is mapped.  In the call to xselectevent, one can
  91. see the one-to-one translation between Xlib constants and case-insensitive
  92. Scheme globals.
  93.  
  94. Following this setup is the event loop.  Here, one can see structure access in
  95. action.  The function xevent-type extracts the type from an XEvent structure.
  96. Once the particular event type has been discovered, the appropriate access
  97. functions can be used.  Thus on a button press event, the coordinates of the
  98. button can be extracted by xevent-xbutton-x and xevent-xbutton-y.  It also
  99. contains one example of the use of an augmented interface, the call to
  100. ylookupstring. Here, a simplified version of XLookupString returns the key
  101. string in a straight-forward manner.  To differentiate such functions from the
  102. standard Xlib interfaces, they have the x in their name replaced by y.
  103.  
  104.  
  105. Xlib Constants
  106. --------------
  107.  
  108. Having given a flavor of the Xlib interfaces in this example, it is now
  109. appropriate to examine their translation to Scheme in detail. The simplest
  110. items are those which are unsigned integer constants. These are found in such
  111. files as X.h, Xatom.h, and Xutil.h.  These are translated on a one-to-one basis
  112. to top level Scheme values which have the same name and value.  Inspite of the
  113. fact that Scheme is insensitive to case, this translation has only caused
  114. problems in translating the constants found in Xkeysym.h.  There, there are
  115. symbols for upper case letters of the form XK_A and symbols for lower case
  116. letters of the form XK_a.  In order to get around this, XK_A is represented as
  117. xk_a and XK_a is represented as xk_lca.
  118.  
  119.  
  120. Simple Data Types
  121. -----------------
  122.  
  123. Many objects in Xlib are defined by the type XID which in turn is defined as an
  124. unsigned long value.  Examples of such objects are Window, Drawable, Font,
  125. Pixmap, Cursor, Colormap, GContext, and KeySym.  These are represented in
  126. Scheme as positive integers.
  127.  
  128.  
  129. Unions and Structs
  130. ------------------
  131.  
  132. The Scheme interfaces provide functions to create and access user visible Xlib
  133. structs and unions.  For example, Xcolor which is defined as:
  134.  
  135.     typedef  struct{
  136.              unsigned long pixel;
  137.              unsigned short red, green, blue;
  138.          char flags;
  139.              char pad;
  140.     } XColor;
  141.  
  142. is handled within Scheme as follows.  An instance of an XColor struct is
  143. represented by a pair consisting of the type tag XCOLORP (denoting a pointer to
  144. an XColor struct) and either a string or a number.  The first form is used to
  145. represent an XColor structure within the Scheme system, and the second is used
  146. to denote one within Xlib.
  147.  
  148. An instance of XColor is created by the function:
  149.  
  150.     (MAKE-XCOLOR)
  151.  
  152. which returns a pair of the form:  (XCOLORP . "").  Any object may be tested to
  153. see if it is a pointer to an XColor struct by:
  154.  
  155.     (ISA-XCOLORP? <any>)
  156.  
  157. For example, (ISA-XCOLORP? (MAKE-XCOLOR)) evaluates to #T.
  158.  
  159. Fields within an XColor struct may be accessed by the following functions:
  160.  
  161.     (XCOLOR-PIXEL <xcolor>)
  162.     (XCOLOR-RED <xcolor>)
  163.     (XCOLOR-GREEN <xcolor>)
  164.     (XCOLOR-BLUE <xcolor>)
  165.     (XCOLOR-FLAGS <xcolor>)
  166.     (XCOLOR-PAD <xcolor>)
  167.  
  168. Fields within an XColor struct may be set by:
  169.  
  170.     (XCOLOR-PIXEL! <xcolor> <value>)
  171.     (XCOLOR-RED! <xcolor> <value>)
  172.     (XCOLOR-GREEN! <xcolor> <value>)
  173.     (XCOLOR-BLUE! <xcolor> <value>)
  174.     (XCOLOR-FLAGS! <xcolor> <value>)
  175.     (XCOLOR-PAD! <xcolor> <value>)
  176.  
  177.  
  178. Simple Arrays
  179. -------------
  180.  
  181. A simple array is an array whose elements are not union or struct objects.
  182. Such array types have names ending in A.  For example, UNSIGNEDA is type of an
  183. array of unsigned integers.  One can make an new instance of an array of
  184. unsigned integers by:
  185.  
  186.     (MAKE-UNSIGNEDA <length>)
  187.  
  188. test if an object is a pointer to such an array by:
  189.  
  190.     (ISA-UNSIGNEDAP? <any>)
  191.  
  192. and determine the number of objects in the array by:
  193.  
  194.     (UNSIGNEDA-LENGTH <unsignedap>)
  195.  
  196. Entries in such an array can be accessed by:
  197.  
  198.     (UNSIGNEDA <unsignedap> <index>)
  199.  
  200. and values set in entries by:
  201.  
  202.     (UNSIGNEDA! <unsignedap> <index> <value>)
  203.  
  204. Finally, one can convert between lists and arrays by:
  205.  
  206.     (UNSIGNEDA->UNSIGNED-LIST <unsignedap>)
  207.     (UNSIGNED-LIST->UNSIGNEDA <list of unsigned numbers>)
  208.  
  209. Another type of array often used with Xlib is CHARA which is an array of
  210. unsigned 8-bit integers.  Similar creation and access procedures exist for it.
  211.  
  212.  
  213. Arrays of Struct and Union types
  214. --------------------------------
  215.  
  216. Functions for operating on arrays of structures are defined in a similar
  217. manner.  Here though, functions are not defined which allow access to fields in
  218. the structures while they are in the array.  Thus for the type XColor, the
  219. following functions are defined:
  220.  
  221.     (XCOLORA-LENGTH <xcolorap>)
  222.     (XCOLORA->XCOLOR-LIST <xcolorap>)
  223.     (XCOLOR-LIST->XCOLORA <list of xcolorp>)
  224.  
  225.  
  226. Available X11 Data Definitions
  227. ------------------------------
  228.  
  229. Using these techniques, the data definitions found in the following files have
  230. been converted:
  231.  
  232.     X.h
  233.     Xatom.h   
  234.     Xlib.h
  235.     Xresource.h
  236.         Xutil.h
  237.     cursorfont.h
  238.     keysymdef.h      (LATIN1 and DEC Private are only options)
  239.  
  240.  
  241. Utility Functions
  242. -----------------
  243.  
  244. Several utility functions have been constructed to assist the user in
  245. manipulating pointers and bit masks for the Xlib interfaces.  They are:
  246.  
  247. (NULL-POINTER? <x>)
  248.     predicate which returns #T iff <x> is a null pointer.
  249.  
  250. (POINTER-TYPE <x>)
  251.     returns the type name of the pointer <x>.
  252.  
  253. (POINTER-VALUE <x>)
  254.     returns the pointer value of the pointer <x>.
  255.  
  256. (TYPE/VALUE->POINTER type value)
  257.     constructs a pointer with type <type> and value <value>.  This
  258.     function is commonly used to construct "magic" pointer values, such
  259.     as visual pointer with the value copyfromparent for a call to
  260.     xcreatewindow.
  261.  
  262.  
  263. Xlib Procedure Interfaces
  264. -------------------------
  265.  
  266. Having described the data representation conventions, it is now appropriate to
  267. turn to the procedure interfaces.  Using a few simple conventions, access to
  268. all procedures defined in the book "X Window System" by Gettys, Newman, and
  269. Scheifler has been provided from Scheme.  Efforts have been made to not change
  270. how these functions act so that existing documentation can be used.
  271.  
  272. The argument passing conventions are:
  273.  
  274.     - Xlib arguments which are null terminated strings can be
  275.       supplied as Scheme strings.
  276.  
  277.     - Xlib arguments which return a value of known size are
  278.       omitted.  For example, one does not call xnextevent with a
  279.       pointer to an XEvent object.  However, one must provide the
  280.       the return arguments for XAllocColorCells as the array and
  281.       its length are computed at runtime.
  282.  
  283.     - Xlib arguments which are pointers to some object must be of
  284.       the correct object type.  
  285.  
  286. The value return conventions are:
  287.  
  288.     - Xlib procedures which do not return a value, return #F.
  289.  
  290.     - Xlib procedures which return a single value, return it.
  291.  
  292.     - Xlib procedures which return multiple values return them as
  293.       a list.
  294.  
  295.     - Xlib procedures which return a pointer to a null terminated
  296.       string return a Scheme string, unless the user must call to
  297.       XFree to return the string in which case a charAP pointer is
  298.       returned.
  299.  
  300.  
  301. Augmented Xlib Procedure Interfaces
  302. -----------------------------------
  303.  
  304. As earlier noted, a few functions have been augmented by adding additional
  305. procedural interfaces.  These procedures are identified by the fact that their
  306. names start with Y rather than X.  In some cases, the Xlib versions still
  307. exist, but in others they do not as the interface was not appropriate for
  308. access from Scheme.  The functions that exist to date are:
  309.  
  310. (YFREE <any-pointer>)
  311.     returns storage, where <any-pointer> is either a tagged or
  312.     untagged pointer.
  313.  
  314. (YQUERYTREE <display-ptr> <window>)
  315.     returns a list of three    elements:  the root window, the parent
  316.     window of <window>, and a list of the children of <window>.
  317.  
  318. (YGETATOMNAME <display-ptr> <atom>)
  319.     returns a string which is the name of <atom>.
  320.  
  321. (YLISTPROPERTIES <display-ptr> <window>)
  322.     returns a list of atoms which indicate the properties that are
  323.     associated with <window>.
  324.  
  325. (YLISTFONTS <display-ptr> <pattern> <maxnames>)
  326.     returns a list of font names (less than or equal to <maxnames>
  327.     in length) which match <pattern>.
  328.  
  329. (YLISTFONTSWITHINFO <display-ptr> <pattern> <maxnames>)
  330.     returns a list of  lists (less than or equal to    <maxnames> in
  331.     length) which match <pattern>.  Each list element is a list
  332.     of a font name and an XFontstruct.
  333.  
  334. (YSETFONTPATH <display-ptr> <directories>)
  335.     sets the font search path to the list of strings
  336.     <directories>.
  337.  
  338. (YGETFONTPATH <display-ptr>)
  339.     returns the list of directories which is the current font
  340.     search path.
  341.  
  342. (YLISTINSTALLEDCOLORMAPS <display-ptr> <window>)
  343.     returns a list of the currently installed colormaps.
  344.  
  345. (YNEXTEVENT <display-ptr> <event>)
  346.     returns the next event in the event structure <event>.
  347.  
  348. (YSELECT <display-ptr> <input-port>... <seconds> <microseconds>)
  349.     waits up to <seconds> <microseconds> for events for <display-ptr>
  350.     or input on one of the <input-port>'s.  If events arrive then
  351.     <display-ptr> is returned, if input arrives then the appropriate
  352.     <input-port> is returned, otherwise #F is returned. 
  353.  
  354. (YGETMOTIONEVENTS <display-ptr> <window> <start> <stop>)
  355.     returns a list of motion events.  Each event is a list of
  356.     three elements:  time, x-position, and y-position.
  357.  
  358. (YSETSTANDARDPROPERTIES <display-ptr> <window> <name> <icon_string>
  359.             <icon_pixmap> <commands> <hints>)
  360.     sets the <window>'s standard properties.  Arguments are as
  361.     expected by XSetStandardProperties, except that <commands> is
  362.     a list of strings.
  363.  
  364. (YFETCHNAME <display-ptr> <window>)
  365.     returns the <window>'s name or #F if it is unnamed.
  366.  
  367. (YGETICONNAME <display-ptr> <window>)
  368.     returns the <window> icon's name or #F if it is unnamed.
  369.  
  370. (YSETCOMMAND <display-ptr> <window> <commands>)
  371.     sets the <window>'s commands to the list of strings
  372.     <commands>.
  373.  
  374. (YGETWMHINTS <display-ptr> <window>)
  375.     returns either the XWMHints for <window> or #F when no hints
  376.     have been provided.
  377.  
  378. (YSETICONSIZES <display-ptr> <window> <iconsizelist>)
  379.     sets the icon sizes to the list of XIconSize structures.
  380.  
  381. (YGETICONSIZES <display-ptr> <window>)
  382.     returns either a list of XIconSize hints, or #F when no hints
  383.     have been provided.
  384.  
  385. (YSETCLASSHINT <display-ptr> <window> <name-class>)
  386.     sets the <window> class hint to the list of two strings
  387.     <name-class>.
  388.  
  389. (YGETCLASSHINT <display-ptr> <window>)
  390.     returns either a list of <window> name and class, or #F when
  391.     no class hints have been supplied.
  392.  
  393. (YLOOKUPSTRING <event>)
  394.     returns the keyboard string associated with the event.
  395.  
  396. (YLOOKUPSTRING <event> #T)
  397. (YLOOKUPSTRING <event> #T <xcomposestatus>)
  398.     returns a list consisting of the keyboard string and the
  399.     KeySym associated with the event.
  400.  
  401. (YLOOKUPSTRING <event> #F <xcomposestatus>)
  402.     returns a list of the keyboard string associated with the
  403.     event and #F.
  404.  
  405.  
  406. Availability
  407. ------------
  408.  
  409. The Xlib interfaces are found in Scheme->C interpreters named scixl.  Libraries
  410. containing the interfaces scxl.a.  In order to correctly link with the
  411. interfaces, a compiled program must include a (with xlib) clause in its module
  412. expression.  When a program is compiled which uses these interfaces, warnings
  413. will be generated as there are no external declarations.  Stand-alone programs
  414. produced in this manner are large as they contain all the Xlib interfaces.
  415.  
  416. Smaller programs can be produced by having the application include the inline
  417. versions of the interfaces found in the .sch files and then linking with the
  418. appropriate object files.
  419.